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PREFACE 



This reference publication describes the Multiprogramming Support (MPS) 
utility macro-instructions available with the Disk and Tape Operating 
Systems. 

It is intended as a guide for the programmer using the utility macro- 
instructions to create simple file-to-file routines for operation in a 
multiprogramming environment under the Disk or Tape Control Programs, as 
described in the System Control and System Service publications listed 
on the cover page of this publication. 

This publication deals with utility macro-instructions, source lan- 
guage program illustrations for generating a utility program via these 
macro-instructions, and the process for the assembly and initiation of 
generated utility programs. 
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PURPOSE OF THE MPS UTILITY MACRO-INSTRUCTIONS 

The utility macro-instructions provide the user of the System/36 Disk 
or Tape Operating System with a direct and easy means of generating effi- 
cient file-to-file utility programs tailored to the user's specific needs, 
The generated utility programs are designed to operate as foreground pro- 
grams within the multiprogramming environment of the Disk or Tape Oper- 
ating System, but can also operate as background programs. 

Multiprogramming Support (MPS) has been provided in the Disk and Tape 
Operating Systems for the purpose of increasing total system throughput. 
In a single-program environment, storage available to the system may not 
be efficiently utilized, I/O channel utilization may not approach 
capacity, and many I/O devices attached to the system may be idle. More- 
over, in a single-program environment, the program under execution fre- 
quently cannot utilize the CPU until some event has been satisfied. Most 
typically, this event is the completion of an I/O request * 

The utility programs created by means of the MPS utility macro- 
instructions perform file-to-file operations concurrently with the exe- 
Icution of other programs. A typical use of a utility program generated 
by means of the MPS utility macro-instructions would be tape-to-printer 
operation executed concurrently with normal batched job processing. 

Utility programs generated via the utility macro-instructions offer 
several distinct advantages over other utility programs. 
These are: 

• ability to add optional user code 

• self-relocating capability of generated utility programs 

• simple parameter selection 



SCOPE OF THE MPS UTILITY MACRO-INSTRUCTIONS 

Utility programs can be generated via utility macro-instructions to sup- 
port any combination of the following media: 



/ card \ , card 

\ tape / to \ tape 

I \ \ ■ 

\ disk ' i disk 



printer ' 



In addition, utility macro-instructions provide the ability to write and/ 
or read using the IBM 1052 Printer-Keyboard. 

The customer is given the choice of generating one or more utility 
programs for each type of file-to-file operation; the number of programs 
being a function of his requirements. 
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The generated utility programs do not require control information from 
the operator or job input stream, unless it is required by optional user- 
supplied routines. 

MACHINE REQUIREMENTS 

The minimum machine configuration for the generation of MPS utility pro- 
grams is the minimum system configuration required to assemble a pro- 
gram in DOS/360 or TOS/360. 

FOR SYSTEM RESIDENCE 

• IBM 2311 Disk Storage Drive (DOS/360) , or 

• IBM 2401, 2402, 2403, 2404, and 2415 Magnetic Tape Drives (TOS/360). 
A 7-track tape drive, with the Data Conversion Feature, may be used, 
but 9-track is recommended. 

FOR CONTROL-STATEMENT LOADING 

• IBM 1052 Printer-Keyboard, or 

• IBM 1442 Card Reader, or 

• IBM 2501 Card Reader, or 

• IBM 2520 Card Reader, or 

• IBM 2540 Card Read-Punch, or 

• IBM 2311 Disk Storage Drive, or 

• IBM 2401, 2402, 2403, 2404 and 2415 Magnetic Tape Drives. 

Note that foreground programs can only utilize a printer-keyboard and a 
card reader for control statement loading. 

FOR OPERATOR-COMMUNICATION 

• IBM 105 2 Printer-Keyboard 

FOR FOREGROUND UTILITY PROGRAM OPERATIONS 

• IBM System/360 processing unit with a minimum of 32K bytes of main 
storage. 

• Input/Output devices required by the specific program. Supported de- 
vices include: 

IBM 105 2 Printer-Keyboard 

IBM 1442 Card Reader 

IBM 2501 Card Reader 

IBM 2520 Card Reader 

IBM 2 54 Card Reader 

IBM 1442 Card Punch 
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IBM 2520 Card Punch 

IBM 2540 Card Punch 

IBM 1403 Printer 

IBM 1404 Printer (continuous forms only) 

IBM 1443 Printer 

IBM 1445 Printer 

IBM 2311 Disk Storage Drive 

IBM 2401, 2402, 2403, 2404 and 2415 Magnetic Tape Drives. For tape 
input and/or output, the utility macro-instructions require the 
optional Supervisor "set mode" facility, with mode indicated on the 
ASSGN statements, where applicable. (Refer to System Control and 
System Service and System Generation and Maintenance publications 
listed on the front cover,) 



introduction 



UTILITY PROGRAM GENERATION 



This section describes concepts and procedures relating to the genera- 
tion of a utility program via the MPS utility macro-instructions. The 
section is divided into three main parts. The first part deals with gen- 
eral programming information relative to the coding of source language 
statements. The second part presents detailed information on the macro- 
instruction prototype statements. For convenient presentation, the 
macro-instructions are divided into an input group and an output group. 
The third part presents examples of source-language programs for file-to- 
file operations, illustrating the use of the MPS utility macro- 
instructions. 

The programmer coding required for the generation of a file-to-file 
utility program is minimal. For example, a self-relocating card-to-card 
utility program may be assembled from the following: 



NAME 


OPERATION 


OPERAND 




START 
INCARD 
OUTCARD 
END 






The assembler interprets the macro-instructions and calls in the appro- 
priate macro definition for each macro from the assembler sub-library 
of the source statement library. The macro definition serves to expand 
the single macro-instruction into a series of source statements replacing 
dummy variables with the parameters (if any) specified in the operand 
field of the macro-instruction. 

The object program generated via assembly may be cataloged in the core 
image library. It can be executed as either a foreground or background 
program. 

MACRO-INSTRUCTION FORMAT 

The format of the macro-instruction prototype dictates the form in which 
the macros must be written in the problem program. The following general 
rules apply: 

1. The name field of the macro-instruction may contain a symbolic ad- 
dress, or may be left blank. 

2. The operation field of the macro-instruction must contain exactly the 
same mnemonic operation code as the prototype (for example, INCARD). 

3. The parameters in the operand field of a macro-instruction must be 
written in the same format as those in the operand field of the 
prototype. 

The MPS utility macro-instruction parameters may be written in any 
order. Any parameters that are not required may be omitted. Multiple 
parameters may either be punched on a single card, or on separate cards 
with an alphameric punch in column 72. The parameters must always be 
separated by a comma. 
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The macro-instruction conventions used to illustrate macro-instructions 
are as follows* 

1. Uppercase letters and punctuation marks represent information that 
must be coded exactly as shown. 

2. Lower case letters represent information that must be supplied by the 
programmer. The letter b always indicates one blank space , and 
where a parameter variable is concerned, lower case letters represent 
constants that must be supplied. 

3. Options contained within braces { /represent alternatives; one of 
which must be chosen. 

4. Information contained within brackets [ ] represents an option that 
can be omitted, (depending upon program requirements) . 

5. Underlined elements [~ N0 1 represent an assumed option in the event 

LyesJ 

a parameter is omitted. 

6. An ellipsis (a series of three periods] indicates that a variable 
number of items may be included. 

7. When registers are permitted as register arguments, ["namell the reg- 

L (rj_ J 
ister number must be enclosed within parentheses. 

UTILITY PROGRAM ORGANIZATION 

Each generated utility program may consist of the following components: 

• optional processing sections (user-provided) 

• input sections 

© output sections 

The processing sections consist of optional user routines. Typical func- 
tions performed by user routines might include selecting an output rou- 
tine for each record, editing input data, inserting data into the output 
stream, or initializing parameters for input and output sections. 

The only restriction imposed by the utility macro-instructions on a 
user routine is that it normally must save and restore registers 0, 1, 13, 
14, and 15 used for communication between the input and output sections. 
Register 13 is reserved for future expansion of the utility 
macro-instructions . 

For foreground operations, optional user processing routines incorpor- 
ated into the utility programs must comply with the conditions set forth 
for foreground programs, and must interface with the system as defined 
in DOS/360 and TOS/36Q Control Programs reference publications cited on 
the cover page of this document. 

The input sections of each utility program will normally consist of 
the coding generated by one or more INCARD, INTAPE, INDISK, or INLOG 
macro-instructions . 

Each input macro-instruction generates all required instructions for 
initialization, data input, and buffer area definitions. The initiali- 
zation which primarily consists of the coding required for self- 
relocation, is within the input areas, except for INLOG. INLOG accesses 
a user-provided area for input data, and does not generate a buffer area. 
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The output sections will normally consist of coding generated by one 
or more OUTCARD, OUTAPE , OUTDISK, OUTPRT, or OUTLOG macro-instructions. 

Each output macro-instruction generates an independent output routine 
including instructions for initialization, data output, and buffer area 
definitions. The initialization, which primarily consists of the coding 
required for self-relocation, is within the output areas, except for OUT- 
LOG. OUTLOG accesses a user-provided area, and does not generate a 
buffer area. 



INTERFACE BETWEEN PROGRAM SECTIONS 

A generated utility program will normally be entered at the initializa- 
tion routine of the input section, unless the input section is preceded 
by an optional user routine. Following each read operation, control will 
pass to the output initialization routine or to an optional user routine. 
The address of the input routine reentry point is stored in register 14. 
The output routine normally will do a write operation, and then return 
to an input or user routine via register 14. Provision is made for the 
user to specify multiple outputs by specifying the RETURN=NO parameter 
in the output macro-instruction. 
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Figure 1 shows sample techniques for passing control between the 



INTERFACE 



PROCEDURE 



TTq^-t Rnnf-i rip 1 



Tn Tnnnf Rnntinp 



in a novf coy 



instruction 



Input Routine 



To User Routine 2 
To Output Routine 



via next sequential 

instruction 
via next sequential 

instruction or through 

User Routine 2 



User Routine 2 



To Output Routine 
To Input Routine 



via next sequential 

instruction 
via address in register 

14 



Output Routine 



To User Routine 3 



i To Input Routine 



via next sequential 
instruction with 
RETURN=NO specified 

via address in register 
14 



User Routine 3 



I To User Routine 2 



To Input Routine 



via branch 

via address in register 
14 



Note : All user routines are optional and user-supplied, 



•Figure 1. Techniques for Passing Control Between Utility Program 
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REGISTER USAGE CONVENTIONS 

General registers 0, 1, 14, and 15 are used by the MPS utility macro- 
instructions for both information transmission and control. Regis- 
ters 2 through 12 are restored by each utility macro-generated routine 
Register usage may be summarized as follows: 



REGISTER 


INPUT ROUTINE 


OUTPUT ROUTINE 





Set to record 
address 


Not modified 


1 


Set to length of 
the record 


Not modified 


2-12 


Not modified 


Not modified 


13 


Reserved 


Reserved 


14 


Set to return 
address 


Not modified 


15 


Used as base 
register 


Used as base 
register 



TT-f- -i 1 -i +-\7 Drnrrrsm l^pnoraf- 



Control of the output routines is via zero and/or nonzero values in 
registers and 1 as follows: 



Reg. j Reg. 1 



Output Routine Response 



Comments 



7^0 



7^0 



Write output record 



Normal exit from 
input routine. 



CLOSE tape or disk file 
and end job or 
End job (printer or 
card output) . 



Normal end of data 
signal from input 
routine. 



^0 



Do not write record, 



Requires a user routine 
to generate this condi- 
tion. 



t^O 



Same as for Reg 0=0 and 
Reg 1=0 except no end of 
job. 



Requires a user routine 
to generate this cond. 
tion. 



Normal processing is accomplished by not modifying the contents of 
registers and 1. End of input is indicated by zeros in registers 
and 1. To cancel the output of a record, the user sets register 1 to 
zero, or he returns directly to the input routine (via BR 14) . If the 
output routine finds that only register 1 contains zero, it immediately 
returns to the input routine. If the user wishes to signal end of file 
without signaling end of job, he sets register to zero and register 1 
to some non-zero value. This will cause the output routine to empty 
its buffer areas, CLOSE its output file, and return. 

SELF-RELOCATION 

The utility programs generated by the MPS utility macro-instructions 
are self-relocating. If the optional user routines incorporated into 
the program are not self-relocating, then the resulting utility program 
is not self-relocating and must be linkage-edited for subsequent 
execution at a fixed location of main storage. A self -relocating pro- 
gram is one which can be executed at any location in main storage. A 
self-relocating program normally is given a linkage-edit address of zero, 
For example: 



SOURCE STATEMENTS 

REPRO 

PHASE EXAMPLE, +0 

PRINT NOGEN 

PROGRAM START 

BALR 15,0 

USING *,15 

* ROUTINE TO RELOCATE ADDRESS CONSTANTS 



+0 ORIGIN IMPLIES SELF-RELOCATION 



LA 1,PRINTCCW 

ST l,PRINTCCB+8 

LA 1 , TAPECCW 

ST l,TAPECCB+8 

LA l,EOFTAPE 

ST l,AEOFTAPE 

LA 1,CHA12 

ST 1,ACHA12 

IC 2,PRINTCCW 

LA l,OUTAREA 

ST 1,PRINTCCW 

STC 2,PRINTCCW 

LA 1 , INAREA 

ST 1, TAPECCW 
MVI 



RELOCATE CCW ADDRESS 

IN CCB FOR PRINTER 
RELOCATE CCW ADDRESS 

IN CCB FOR INPUT TAPE 
* RELOCATE***** 

* PROGRAM * 

* ADDRESS * 
****CONSTANTS* 

SAVE PRINT CCW OP CODE 
RELOCATE OUTPUT AREA ADDRESS 

IN PRINTER CCW 
RESTORE PRINT CCW OP CODE 
RELOCATE INPUT AREA ADDRESS 

IN TAPE CCW 
SET TAPE CCW OP CODE TO READ 



TAPECCW, 2 

* MAIN ROUTINE. . .READ TAPE AND PRINT .RECORDS 
READTAPE LA 1,TAPECCB GET CCB ADDRESS 
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EXCP 


(1) 




WAIT 


(1) 




T 
J-l 


10 , AEOFTAPE 




BAL 


14, CHECK 




MVC 


OUTAREA (10) , INAREA 




MVC 


OUTAREA+15(70) ,INAREA+1 




MVC 


OUTAREA+ 9 0(20) , INAREA+ 8 




LA 


1, PRINTCCB 




EXCP 


n ^ 




WAIT 


(1) 




L 


10,ACHA12 




BAL 


14, CHECK 




B 


READTAPE 


CHECK 


TM 


4(1) ,1 




BCR 


1,10 




BR 


14 


CHA12 


MVI 


PRINTCCW, X'8B* 




EXCP 


(1) 




WAIT 


(1) 




MVI 


PRINTCCW, 9 




BR 


14 


EOFTAPE 


EOJ 






CNOP 


0,4 


PRINTCCB 


CCB 


SYS004, PRINTCCW, X' 0400' 


TAPECCB 


CCB 


SYS 001, TAPECCW 


PRINTCCW 


CCW 


9, OUTAREA, X' 20' ,110 


TAPECCW 


CCW 


2, INAREA, X' 20' ,100 


AEOFTAPE 


DC 


A (EOFTAPE) 


APRA1 9 


DC 


A(CHA12) 


OUTAREA 


DC 


CL110' ' 


INAREA 


DC 


CL100' ' 




END 


PROGRAM 



READ ONE RECORD FROM TAPE 

WAIT FOR COMPL. OF I/O 

GET ADDRESS OF TAPE EOF ROUTINE 

GO TO UNIT EXCEPTION SUBROUTINE 

EDIT RECORD 
) IN 
) OUTPUT AREA 

GET CCB ADDRESS 

PRINT EDITED RECORD 

WAIT FOR COMPL. OF I/O 

GET ADDRESS OF CHAN 12 ROUTINE 

GO TO UNIT EXCEPTION SUBROUTINE 

CHECK FOR UNIT EXEC. IN CCB 
YES-GO TO PROPER ROUTINE 
NO-RETURN TO MAINLINE 

SET SK TO CHAN 1 OP CODE 

SK TO CHAN 1 IMMEDIATELY 

WAIT FOR COMPL. OF I/O 

SET PRINTER OP CODE TO WRITE 

RETURN TO MAINLINE 

END OF JOB 

ALIGN CCB'S TO FULL WORD 



The input/output routines also adjust references to optional 
user-supplied locations, the optional "name" operands of macro 
parameters (such as STCTL, RECSIZ, LBL) , etc. 

Except for the macro-instructions INLOG and OUTLOG, the code 
required for self-relocation is placed in an I/O buffer and sub- 
sequently overwritten. All relocation takes place prior to the 
start of I/O operations. 

INTERFACE WITH THE DATA MANAGEMENT FACILITIES 

The standard error-recovery facilities of the DOS/360 or TOS/36 systems 

are used for card readers, 1442 card punch, and printers. For the 2520 

and 2540 card punches, the utility macro-instructions provide error 

recovery. For tape and disk I/O, the system attempts error recovery 

and signals an error to the utility routine only if the error is not 

corrected. 

The standard OPEN and CLOSE transient routines provided in TOS/36 
and DOS/360 are used by the generated utility routines for tape and 
disk files. (Refer to the Supervisor and Input/Output Macros publi- 
cations.) These functions include standard label processing, and for 
files bearing standard labels, alternate tape units, multiple extent 
sequential disk files, and multi-volume tape files. Tape files should 
be properly positioned prior to OPEN and are not repositioned following 
CLOSE. Tape files not bearing standard labels may include multiple- 
volume files and multiple-file volumes; in those cases the operator 
must control processing of additional volumes and/or files. 

The utility programs handle all files as if they were sequentially 
organized. Tape and disk utility macro-instructions process fixed- 
and undefined- length records, blocked or unblocked. The MPS utility 
macros generate instructions for buffer rotation and for optional 
blocking or deblocking. Also, an option is provided in the INTAPE 
macro-instruction for either using checkpoint information as data or 
for bypassing checkpoint records. 

Utility Program Generation 13 



INPUT MACRO- INSTRUCTIONS 



Except for INDISK, the macro-instructions described as follows apply 
equally to the DOS/360 Control Program and the TOS/360 Control Program. 

The following apply to all the input macro-instructions, except INLOG: 

1. The values contained in the "namex" parameters may be set by an optional 
user initialization routine prior to processing each file via the 
macro input routine. 

2. SYSnnn is a programmer logical unit, i.e., nnn is three digits. 

INCARD (CARD INPUT MACRO- INSTRUCT ION ) 

The INCARD macro-instruction causes records to be read from the desig- 
nated card reader. A 160 byte buffer is generated for two input records. 
The user's card input is assumed to be in BCD or EBCDIC format. End-of- 
card input is signaled by an EOF condition on the card reader. 



NAME 



OPERATION 



OPERAND 



[name] 



INCARD 



UNIT= ||YS001 
(SYSnnn 



UNIT= 



fSYSOOl) 
(SYSnnn/ 



This parameter specifies the symbolic name of the input logical unit. 

INTAPE (TAPE INPUT MACRO INSTRUCTION ) 

The INTAPE macro-instruction generates initialization, a file OPEN, a 
tape read routine, an end-of-file test, and a file CLOSE. 



If a tape not bearing standard labels is indicated but the tape con- 
tains label (s), the labels are considered to be data. This permits the 
user to check a nonstandard label via an optional routine. 

Upon encountering each tape mark on a volume not bearing standard labels, 
the operator is given the option to initiate processing of additional files 
or to signal end-of -input. 



NAME 



[name] 



OPERATION 



INTAPE 



OPERAND 



3UFSIZ=n 



,RECSIZ=/ m A 
(namelj 



, UNIT .i|||ooi 



>nnn 



,FILE= 



= /fil« 



enamel 
r) / 

(SKIP ] 
,ERROR= } IGNORE > 
(name 3 j_ 



I ,LBL=name2j 



,CHKPT= 



NO 
name 4 



BUFSIZ=n 

This required parameter specifies the maximum size of an input block and 
is used to allocate buffer space for two blocks of that length. Shorter 
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records can be read, in which case, actual record length is determined 
by the input routine. Longer records will be truncated. The first time 
record truncation occurs, the operator is given the option of canceling 
the job. The minimum buffer size is 2 bytes. 

,RECSIZ=i m 

(namel 

This parameter specifies the size of logical records within blocks. If 
omitted, records are assumed to be unblocked. 

If RECSIZ=m, then m specifies the logical record size and the value 
is assembled into the program. A value of zero for m indicates un- 
blocked records, and is equivalent to omitting the RECSIZ operand. 

If RECSIZ=namel, the content of the fullword symbolic location 
"namel" is interrogated at execution time when the input file is OPENed. 
The value found will be used in subsequent deblocking, unless the value 
is zero. If the value is zero, records are treated as unblocked. 

If records are blocked, any incomplete logical record at the end of a 
block will be transmitted without modification. The first time this con- 
dition occurs, the operator is given the option of canceling the job. 
If the operator chooses to continue, an optional user routine may modify 
or delete the record. 

r,TTNTT=/§XS00l\l 

(SYSnnnJJ 
This parameter specifies the symbolic name of the input logical unit. 



,FILE=j fl 



lenamel 
(r) ) 



This parameter specifies that the file bears standard labels. If omitted 
the file is treated as unlabeled. A register, (r) , may contain the address 
of the eight character filename. (Refer to the // VOL statement described 
in either one of the System Control and System Service publications listed 
on the front cover.) 

[,LBL=name2] 

This parameter specifies what label processing is to be performed. If 
omitted, no user label processing is attempted. If LBL=name2 is specified, 
the FILE parameter must be provided and the full-word area designated 
"name2" will be interpreted to determine user label processing procedures. 
If the area contains a zero value, the file must bear standard labels and 
any optional user-header record (s) will be skipped in positioning the tape 
past the next tape mark. If the area contains a negative value, the file 
is treated as unlabeled. A positive, nonzero value is assumed to be the 
address of a user routine to process user-header or trailer records. This 
address will be relocated, if necessary" by the INTAPE macro. The user 
routine releases control via the LBRET macro instruction. (Refer to the 
Supervisor and Input/Output Macros publications.) 



(SKIP 
,ERROR= \ IGNORE 



)k 



ame 3 ;_ 

The ERROR parameter specifies error-handling procedures after the super- 
visor has detected an error. SKIP causes the input routine to bypass 
any unreadable record. IGNORE causes the error condition to be ignored 
and the record to be processed. If ERROR=name3 is specified, then 
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"name3" must be the symbolic location of a user-provided routine to which 
control is passed when an unreadable record is encountered. When this 
occurs registers and 1 will contain the block address and length, re- 
spectively. If the user returns (via BR 14) with register 1=0, the rec- 
ord is bypassed, but if register 1^0, the record is processed as though 
no error occurred. 

If records are blocked, a user-provided routine (name3) receives 
control only once for each unreadable block. 



r,CHKPT={ N0 .}" 

L tname4J _ 



This parameter specifies the handling of checkpoint records. If omitted, 
checkpoint records will be bypassed. If a tape does not contain check- 
point records, CHKPT=NO should be indicated. If the full-word area, 
symbolically designated "name4" is specified, it will be interrogated at 
execution time, and checkpoint records will be treated like data only if 
the value is nonzero; otherwise checkpoint records will be bypassed. For 
further information on checkpoint, refer to the Supervisor and Input/ 
Output Macros publications. 



INDISK (DISK INPUT MACRO INSTRUCTION ) 

The INDISK macro instruction generates all required initialization, a 
file OPEN, a disk read routine, and an end-of-file test, and a file 
CLOSE. The input unit is determined by the required label information. 
Any key fields on disk input are ignored. 



NAME 



[name] 



OPERATION 



INDISK 



OPERAND 



BUFSIZ=n 



,RECSIZ=/ m 

(namel 



,FILE= { f ±1 ^ ame ) [,LBL=name2] 



(SKIP 
,ERROR=< IGNORE 
(name 3 



BUFSIZ=n 

This required parameter specifies the maximum size of an input block and 
will be used to allocate buffer space for two blocks of that length. 
Shorter records can be read, since actual record length is determined 
by the input routine. 
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Longer records will be truncated. The first time record truncation 
occurs, the operator has the option of canceling the job. Regardless 
of the physical length of records, each record will be read from each 
track within the extents of the file. 



,RECSIZ=i m _\ 



This parameter determines the size of logical records within blocks. If 
omitted, records are assumed to be unblocked. 

If RECSIZ=m then m specifies the logical record size whose value is 
assembled into the program. A value of zero for m indicates unblocked 
records, and is equivalent to omitting the RECSIZ operand. 

If RECSIZ=namel, the content of a full-word, symbolic location, 
"namel", is interrogated at execution time, when the input file is 
OPENed. The value found will be used in subsequent deblocking, unless 
the value is zero. If the value is zero, records are treated as 
unblocked. 

If records are blocked any incomplete logical record at the end of a 
block will be transmitted without modification. The first time this 
condition occurs, the operator has the option of canceling the job. If 
the operator chooses to continue, an optional user routine may modify 
or delete the record. 

,FILE={ fi ^ ame } 

This required parameter identifies label information. A register (r) 
may contain the address of the eight character filename. Refer to the 
// VOL statement in either System Control and System Service publications 
listed on the front cover. 

[ ,LBL=name2] 

This parameter specifies user label processing procedures. The disk 
file must bear a standard label. If omitted, any additional user labels 
are treated as data. If LBL=name2 is specified, the full-word area 
symbolically designated "name2", will be interpreted prior to OPEN, to 
determine label processing procedure. If the area contains zero or is 
negative, files must bear standard labels and additional user labels 
will be treated as data, just as though the parameter were omitted. 
Otherwise, the area must contain the address of a user routine to process 
additional user labels. This address will be relocated, if necessary by 
the INDISK macro. The user routine releases control via the LBRET macro 
instruction. (Refer to the Supervisor and Input/Output Macros publications.) 



(SKIP 
,ERROR=< IGNORE 
(name3 



This parameter specifies error-handling procedures after the supervisor 
has detected an error. SKIP causes the input routine to bypass any 
unreadable record. IGNORE causes the error condition to be ignored and 
the record to be processed. If ERR0R=name3 is specified, then "name3" 
must be the symbolic location of a user-provided routine to which con- 
trol is passed when an unreadable record is encountered. When this 
occurs, registers and 1 contain the block address and length respec- 
tively. If the user returns with register 1=0 (via BR 14) , the rec- 
ord is bypassed, but if register 1^0, the error condition is ignored. 
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If records are blocked prior to processing of the block, a user- 
provided routine (name3) receives control only once for each unreadable 
block. 



INLQG (PRINTER- KEYBOARD INPUT MACRO INSTRUCTION) 

The INLOG macro-instruction provides the facility to read information 
from the IBM 1052 Printer-Keyboard assigned to SYSLOG. 



NAME 


OPERATION 


OPERAND 


[name] 


INLOG 


BUFFER=i^ m ® 1 |CcOUNT=i I J r 11 



BUFFER= 



jname 



x } 



This required parameter designates the location of the user's buffer 
area (namel) or a register (r, ) containing the buffer address. 



[,COUNT=|« }] 



This parameter specifies the number of characters, or the register (r c ) 
containing the number of characters, to be read. If BUFFER=namel, the 
COUNT parameter may be omitted, in which case the number of characters 
read will be equal to the buffer length. The number of characters may 
not exceed 256. If the number of typed characters exceeds the indicated 
count, the message is truncated. Register 1 contains the number of 
characters read, not including end of block (b) . 

Note : No check will be made to ensure that SYSLOG is assigned to a 
readable 1052. 
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OPERATION 


OPERAND 


MUST BE INCLUDED 


REMARKS 


INCARD 


/SYSOOl) 
UNIT -isYSnnn} 




If other than SYS001 


nnn = the pro- 




L J J 


is wanted. 


grammer logical 
unit containing 
input. A 160 byte 
buffer is generated. 


INTAPE 


BUFSIZ=n 


For each file. 


n=maximum size of 
input block. A 
buffer of 2n bytes 
is generated. 


,RECSIZ={^ amel l 




If logical record 


m=iogical record size 


- 






size within blocks 


namel=symbolic 






is to be specified. 


location containing 
logical record size. 
If omitted or value=0 , 
records are treated 
as unblocked. 


m /SYS001) 










/ UNIT-[ SYSnnn J 




If other than SYS0 01 


nnn = the programmer 






is wanted. 


logical unit contain- 
ing input. 


,FILE= j filename l 


For each file bear- 


Identifies the filename 




L * (r) U 


ing standard labels. 


for label processing. 
r=register pointing to 
the 8 character filename. 




[,LBL=name2] 


If special label 


name2=full-word area to 






processing is desired. 


be interpreted. If 
valuT5=0 , standard labels 
are assumed and user la- 
bels are bypassed. If 
value is positive, value= 
address of user HDR re- 
cord processing routine. 


! 1 

S ] 


If value=negative, or the 


j ! 


parameter is omitted no 


i | 


label processing is 


, 






attempted. 


(SKIP j 










, ERROR=\ IGNORE > 
(name 3 ) 




If read errors are 


SKIP=bypass any unread- 






not to be entirely 


able block. IGNORE= 






ignored. 


ignore error condition. 
name3=symbolic address 
of a user's routine for 
unreadable block proc- 
essing. 


r,CHKPT=/^ me4 l" 




If checkpoint rec- 


name4=full-word area 




\NO /_ 




ords are to be 


to be interpreted. If 






treated as data. • 


value=non-zero, check- 
point will be treated 
as data. If value=zero 
or the parameter is 



Figure 2. Summary of Input Macro Instructions (Page 1 of 2) 
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OPERATION 



OPERAND 



MUST BE INCLUDED 



REMARKS 



omitted, checkpoint 
records are bypassed. 
If CHKPT=NO, check- 
point records are 
treated as data. 



INDISK 



BUFSIZ=n 



For each file. 



n=maximum size of 
input block. A buffer 
of 2n bytes is gen- 
erated. 



_/m \ 
,RECSIZ-^ ngme ]_J 



If logical record 
size within blocks 
is to be specified, 



m=logical record size 
name l=symbo lie address 
containing logical 
record size. If omit- 
ted or value=0, records 
are treated as unblocked. 



,FILE 



■n 



enamel 



For each file. 



Identifies the filename 
for label processing. 
r=register pointing to 
an 8 character filename, 



[,LBL=name2] 



If additional user 
label processing 
is desired. 



name2=full-word area 
(designated name2) to 
be interpreted. If 
value=0 , additional 
user labels are treated 
like data. Otherwise, 
value is address of 
user's HDR label proc- 
essing routine. 



(SKIP ) 

,ERROR=< IGNORE | 

(name 3 J 



If read errors are not 
to be entirely 
ignored. 



SKIP=bypass any unread- 
able block. IGNORE= 
ignore error condition. 
name3=symbolic address of 
a user's routine for 
unreadable block 
processing. 



INLOG 



BUFFER= 



namel 
(rvj 



For each input via 
the 1052. 



namel=symbolic location 

of the user's buffer 

area. 

reregister containing 

the buffer address. 



, COUNT= 



-frc>}] 



If BUFFER=(r b ) 



n=number of characters 

to be read. 

r =register containing 

the number of characters 
to be read. 



Figure 2. Summary of Input Macro-Instructions (Page 2 of 2) 
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OUTPUT MACRO- INSTRUCTIONS 



Except for OUTDISK, the macro-instructions described as follows apply 
equally to the DOS/360 Control Program and the TOS/360 Control Program. 

The following apply to all output macros except OUTLOG: 

1. The values contained in the "namex" parameter operands may be set 
by an optional user initialization routine prior to processing eaci 
file via the output macro instruction. 

2. SYSnnn is a programmer logical unit, i.e., nnn is three digits. 



OUTCARD (CARD OUTPUT MACRO-INSTRUCTION) 



The OUTCARD macro-instruction causes records to be punched on cards . 



NAME 



OPERATION 



OPERAND 



[name] 



OUTCARD 



/SYS002\ 
UNIT= \SYSnl^/ 



/YES) 
,RETURN=| S q-| 



( no y 

,STCTL=<YES > 
(namel). 



( 1442 ) 

,DEVICE=<(2520 > 

(2540) 



/SYS002) 

UNIT = SYSEnH 



This parameter specifies the symbolic name of the output unit, 



(NO 
,STCTL=<YES 

(namel) _ 



This parameter controls stacker selection. If STCTL=NO, unconditional 
selection of pocket 2 is implied, and input records will be punched with 
the first character in column 1. 



If STCTL=YES, stacker selection is controlled by the first character 
of each input record (V or W, for pockets 1 and 2 respectively) , and 
the input records will be punched with the second character in column 1 
of the output records . 

If STCTL=namel, then "namel" specifies the symbolic location of a 
full-word area which is interpreted at execution time to determine 
whether stacker selection is to be provided. If the word contains zero, 
selection of pocket 2 is unconditional, as though STCTL=NO had been 
specified. If the word contains a nonzero value, stacker selection be- 
comes effective, as though STCTL=YES had been specified. The value is 
checked prior to punching each card. 
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144 



0> 



,DEVICE=<252u/ 
12540) 

This parameter controls error-recovery procedures. The parameter must 
be specified if the card punch is a 2520 or 2540, so that the appropri- 
ate error-recovery code will be provided in the output routine. The 
1442 error recovery routines are supplied by the DOS/360 or TOS/360 
control program. 

Notes : 

1. A buffer will be generated for 2 output records (160 bytes) for 1442 
and 2520, or for 3 output records (240 bytes) for 2540. 

2. When stacker selection is in effect, any leading character other 
than V (pocket 1) or W (pocket 2) will result in selection of 
pocket 2, and the leading character will be truncated. The first 
time this occurs, the operator has the option of canceling the job. 
Stacker-select characters V and W are not punched. 

3. If a record that is to be punched exceeds 80 characters, not 
including stacker select control (first character) , the record will 
be truncated. The first time this condition occurs, the operator 
has the option of canceling the job. 



/YES\1 

This parameter governs the return to the input section or optional user 
section. If RETURN=YES , a return to the input or user routine is pro- 
vided via register 14. RETURN=NO signifies that the user's own coding 
or additional output utility macros will follow. 



OUTAPE (TAPE OUTPUT MACRO- INSTRUCT ION) 

The OUTAPE macro instruction generates initialization, a file OPEN, a 
tape write routine, an end-of-file test, and a file CLOSE. 

If tape not bearing standard labels is indicated, no check is made 
for labels, and any label would be over-written by the first output 
record. At end of job the program writes two tape marks. The tape 
will then be backspaced so that it is positioned immediately after the 
first tape mark. 

Upon encountering end-of-reel on each tape not bearing standard 
labels, a tapemark is written, the tape is rewound and unloaded, and the 
operator is instructed to mount an additional volume to be used for 
further output. 



NAME 



OPERATION 



OPERAND 



[name] 



OUTAPE 



j m i . SYS002I 

BUFSIZ=n [,BLK=jnamel[J |rUNIT=< SYSnnn | 

[ ,LBL=name2J 



jfilename.i 
,FILE=^ (r) }j 



/YES\ 
,RETURN=jj|o-|J 



BUFSIZ=n 

This required parameter specifies the maximum size of an output block 
and is used to allocate buffer space for two blocks of that length. The 
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value of n must not be less than 20. This is the shortest record that 
is written. If unblocked records that are to be written are longer than 
the buffer space provided, they will be truncated. The first time this 
occurs, the operator is given the option of canceling the job. 



_' BLK -\namel/ 



This parameter determines the number of logical records per output 
block. If the parameter is omitted, the output records are unblocked, 



If BLK=m, then rn specifies the blocking factor which is assembled 
into the program. A value of zero or one for m indicates unblocked 
records, and is equivalent to omitting the BLK operand. 

If BLK=namel, the content of the full-word symbolic location, "namel" 
is interrogated at execution time when the file is OPENed. The value 
found is used as the blocking factor, unless the value is zero or one. 
If it is zero or one, output is unblocked. 

Regardless of the blocking factor specified, the accumulated records 
are written immediately, as a block, if the next record threatens to 
exceed allocated buffer space. The first time this condition is 
encountered, the operator has the option of canceling the job. 

The final output block may be shorter than previous blocks due to 
termination of input. 

/SYS002\" 
,UNIT=| SYSnnn }_ 

This parameter specifies the symbolic output unit. 



f (filename)" 
L,FILE={ (r) }_ 



This parameter specifies that the file bears standard labels. If 
omitted the file is treated as unlabeled. A register (r) may contain 
the address of the eight character filename. Refer to the // VOL 
statement contained in System Control and System Service publications 
listed on the front cover. 

[,LBL=name2] 

This parameter specifies what label processing is to be performed. If 
omitted, no user label processing is attempted. If LBL=name2 is speci- 
fied, the FILE parameter must be provided and the fullword area desig- 
nated "name2" will be interpreted to determine user label processing 
procedures. If the area contains a zero value, no user label processing 
is attempted and the file must bear an IBM Standard Label. If the 
area contains a negative value, the file is treated as unlabeled. A 
positive, nonzero value is assumed to be the address of a user routine 
to create user-header records or user- trailer labels (EOF and EOV) . 
This address is relocated if necessary by the OUTAPE macro. The user 
routine releases control via the LBRET macro-instruction. (Refer to 
the Supervisor and Input/Output Macros publications.) 
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[,RETURN={|§^J 

This parameter governs the return to the input routine or to the 
optional user routine. If RETURN=YES a return to the input or user 
routine is provided via register 14. RETURN=NO signifies that the 
user's own coding or additional output utility macro-instructions will 
follow. 

OUTDISK (DISK OUTPUT MACRO-INSTRUCTION) 

The OUTDISK macro-instruction generates initialization, a file OPEN, a 
disk write routine, an end-of-file test, and a file CLOSE. The input 
unit is determined by the required label information. All records 
written on disk will have a key length of zero. 



NAME 



OPERATION 



OPERAND 



[name] 



OUTDISK 



BUFSIZ=n [,BLK={™ amel }_ 

enamel 
(r) J 



_ jfilenamel 



,FILE 



( FULL 
,FORMAT=<n 

(name4;_ 



,LBL=name2 



(IGNORE) 



' ERR0R= tn^mel-) 



,RETURN=lXlS 
\N0 



BUFSIZ=n 

IThis required parameter specifies the maximum size of an output block 
[and allocates buffer space for two blocks of that length. Shorter rec- 
lords can be generated. The value of n must not exceed 3625. 

If unblocked records to be written are longer than the buffer 
space provided, they are truncated. The first time this occurs, the 
operator has the option of canceling the job. 



,BLK= 



(name 



i}' 



This parameter determines the number of logical records per output 
block. If omitted, output records are unblocked. 

If BLK=m, then m specifies the blocking factor to be assembled into 
the program. A value of zero for m indicates unblocked records, and is 
equivalent to omitting the BLK operand. 

If BLK=namel, the content of the full-word symbolic location, "namel" 
is interrogated at execution time when the file is OPENed. The value 
found will be used as the blocking factor, unless the value is zero or 
one. If zero or one, output is unblocked. 

Regardless of the blocking factor specified, an accumulation of rec- 
ords are written immediately, as a block, if the next record threatens 
to exceed allocated buffer space. Unblocked records that are too large 
for the buffers are truncated. The first time each condition is encoun- 
tered, the operator has the option of canceling the job. The final out- 
put block may be shorter than previous blocks due to termination of 
input. 
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:={ fi: 



,FILEH ril ename^ 



iThis required parameter identifies label information and is required 
for files bearing standard labels. A register (r) may contain the 

[address of the eight character filename. Refer to the // VOL statement 
contained in either System Control and System Service publications 
listed on the front cover. 

[,LBL=name2] 

This parameter specifies user label-handling procedures . The disk files 
must bear standard labels with or without additional user labels. If 
the LBL parameter is omitted, no provision is made for user labels. If 
LBL=name2 is specified, the full-word area symbolically designated 
n name2" will be interpreted prior to OPEN, to determine label processing 
procedure. If the area contains zero, no provision is made for user 
labels. A nonzero value must be the address of a user routine to create 
user labels. This address will be relocated, if necessary, by the 
OUTDISK macro. The user routine releases control via the LBRET macro 
i instruction. (Refer to Supervisor and Input/Output . ) 

Note : All records written on disk will have a key length of zero. 

, ERR0R ={i2S°M' 

(name 3 J 

This parameter specifies error-handling procedures after the supervisor 
has detected an error. If IGNORE is specified, no attempt is made to 
verify disk output. If ERR0R=name3 is specified, then "name3" must be 
the symbolic location of a user-provided routine to which control is 
passed when each error occurs. The user may return to the output 
routine via BR 14. Regardless of user action, the output error will be 
ignored. 

( FULL ] 

,FORMAT=<n ( 

(name A, 

This parameter specifies the number of records to be written on a track. 
FULL indicates that as many records as possible are to be written 
(within the 3625 byte capacity) on each track. If F0RMAT=n is specified, 
the n is the fixed number of records to be written per track. If n is 
so large as to cause a track overflow condition, each track will contain 
as many records as possible, but the number will not exceed n. 

If F0RMAT=name4 , the content of the full-word symbolic location 
"name4", is interrogated when the file is OPENed to determine the number 
of records to be written per track. If the value of n is greater than 
zero it is assumed to indicate the number of records per track. If the 
value is less than (or equal to) zero, it is equivalent to specifying 
FULL or omitting the parameter. 
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/YES) 
,RETURN=| M o-| 

This parameter governs the return to the input routine or user routine. 
If RETURN=YES, a return to the input or user routine is provided via 
register 14. RETURN=NO signifies that user coding or additional output 
utility macro-instructions follow. 



OUTPRT (PRINTER OUTPUT MACRO-INSTRUCTION) 

The OUTPRT macro-instruction causes records of the specified size to be 
output on the line printer. 



NAME 



OPERATION 



OPERAND 



[name] 



OUTPRT 



BUFSIZ=n 



/SYSC 
,UNIT={ SYSnnnJ 



002M (YES) 

— } ,RETURN={^ 




[BUFSIZ=n] 

This parameter specifies the maximum size of an output line, including 
any forms-control character. If this parameter is omitted, the value 
of n is set to 144. Shorter records can be printed. 

If the records that are to be printed are longer than the indicated 
maximum' size, the record is truncated. The first time this condition 
occurs, the operator has the option of canceling this job. 

A buffer will be generated for two output lines (2n bytes) . 



>G 



(SYS002\ 
' UNIT= \SYSHHn7 



This parameter specifies the symbolic name of the output unit, 



/YES) 
,RETURN=|^ -| 



This parameter governs the return to the input routine or user routine. 
I If RETURN=YES, a return to the input or user routine is provided via 
register 14. RETURN=NO signifies that user coding or additional output 
utility macro-instructions follow. 




This parameter pertains to first-character forms control. If this 
parameter is omitted, all output lines are single spaced. If no forms 
control is specified, the first character of each record is printed as 
data. The significance of each of the forms options follows. 
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Type A 

Indication of Type A allows the user to use the character that is the 
command- code portion of the System/360 Channel Command Word used in 
printing a line or spacing the forms. If the character read is not 
one of the following characters, the line will be printed with single 
spacing after printing and no error indication will be given. 





Punch 


8-Bit Code 


Combination 


00000001 


12,9,1 


00001001 


12,-9,-8,-1 


00010001 


H/9^l' 


00011001 


11,9,8,1 


10001001 


12,0,9 


10010001 


12,11,1 


10011001 


12,11,9 


10100001 


11,0,1 


10101001 


11,0,9 


J-\J J-J-\J \J \J J. 


~\ l l n l 


10111001 


12,11,0,9 


11000001 


12,1 


11001001 


12,9 


11010001 


11,1 


11011001 


11/9 


11100001 


11,0,9,1 


00001011 


12,9,8,3 


00010011 


11,9,3 


00011011 


11,9,8,3 


10001011 


12,0,8,3 


10010011 


12,11,3 


10011011 


12,11,8,3 


10100011 


11,0,3 


10101011 


11,0,8,3 


10110011 


12,11,0,3 


10111011 


12,11,0,8,3 


11000011 


12,3 


11001011 


12^0,9,8,3 


11010011 


11 3 


11011011 


12,11,9,8,3 


11100011 


0,3 


00000011 


12,9,3 



after printing 
after printing 
after printing 
after printing 
after printing 
after printing 



Function 

Write (no automatic space) 

Write and space 1 line after printing 

Write and space 2 lines after printing 

Write and space 3 lines after printing 

Write and skip to channel 1 after printing 

Write and skip to channel 2 

Write and skip to channel 3 

Write and skip to channel 4 

Write and skip to channel 5 

Write and skip to channel 6 

Write and skip to channel 7 

Write and skip to channel 8 after printing 

Write and skip to channel 9 after printing 

Write and skip to channel 10 after printing 

Write and skip to channel 11 after printing 

Write and skip to channel 12 after printing 

Space 1 line immediately 

Space 2 lines immediately 

Space 3 lines immediately 

Skip to channel 1 immediately 

immediately 

immediately 

immediately 

immediately 

immediately 

immediately 

immediately 

immediately 



Skip to channel 

Skip to channel 

Skip to channel 

Skip to channel 

Skip to channel 

Skip to channel 

Skip to channel 

Skip to channel 

Skip to channel 10 immediately 

Skip to channel 11 immediately 

Skip to channel 12 immediately 

No OD 
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Type B 

Type B allows the user to use the d-modifier character of the IBM 1401 
carriage-control instruction used in printing a line or spacing forms 

I with a 1401 system. If the character read is not one of the valid 
characters, the line will be printed with single spacing after printing 
and no error indication will be given. The codes are as follows: 



immediate skip to 



Skip after print to 



1 


channel 


1 


A 


channel 


1 




2 


channel 


2 


B 


channel 


2 




3 


channel 


3 


C 


channel 


3 




4 


channel 


4 


D 


channel 


4 




5 


channel 


5 


E 


channel 


5 




6 


channel 


6 


F 


channel 


6 




7 


channel 


7 


G 


channel 


7 




8 


channel 


8 


H 


channel 


8 




9 


channel 


9 


I 


channel 


9 







channel 


10 


7 


channel 


10 


(EBCDIC < 


# 


channel 


11 


. 


channel 


11 




@ 


channel 


12 


H 


channel 


12 


(EBCDIC ( 


d 


immediate space 


d 


after print 


-space 


J 


1 space 




/ 


1 space 






K 


2 spaces 


S 


2 spaces 




L 


3 spaces 


T 


3 spaces 




Typi 


e C 













Type C allows the use of the following codes as first-character, 
forms-control characters. If the character read is not one of the 
valid characters, the line will be printed with single spacing after 
printing. 



Code 

plus (EBCDIC or BCDIC) 

blank 

zero 

1-9 or J-R 



Space or Skip Action 

Suppress space and print 

Print and single space 

Double space, print, and space 

Triple space, print, and space 

Immediate skip to channel 1-9 
(that is, 1 or J=skip to channel 
1; 2 or K=skip to channel 2; etc) , 
print, and then space. 



Type D 

Type D allows the use of the ASA FORTRAN first-character, forms-control 
set. If the character read is not one of the valid characters, the 
line will be printed with single spacing before printing. 

This character control set is used with printed output of TOS/360 
or DOS/360 components. 
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Code 



Space or Skip Action 



blank 




(EBCDIC or BCDIC) 



Space one line before printing 
Space two lines before printing 
Space three lines before printing 
Suppress space before printing 
Skip to Channel 1 before printing 

2 

3 

4 

5 

6 

7 

Skip to Channel 8 before printing 
Skip to Channel 9 before printing 
Skip to Channel 10 before printing 
Skip to Channel 11 before printing 
Skip to Channel 12 before printing 



Skip to Channel 
Skip to Channel 
Skip to Channel 
Skip to Channel 
Skip to Channel 
Skip to Channel 



oerore printing 
before printing 
before printing 
before printing 
before printing 
before printing 



PUTLOG (PRINTER-KEYBOARD OUTPUT MACRO INSTRUCTION) 

The OUTLOG macro instruction provides the facility to write 
information onto the IBM 1052 Printer-Keyboard assigned to SYSLOG, 



NAME 



OPERATION 



OPERAND 



[name] 



OUTLOG 



BUFFER; 



(namel) 
"I (r b )/ 



, COUNT 



-)(r C 



(YES) 
, RETURN= jgQ-j 



Jnamel") 
= I (rfc>)j 



BUFFER 



This required parameter specifies the location of the user's buffer 
area, namel, or a register, {r^) , containing the buffer address. 



, COUNT 



= {<"c'} 



This parameter specifies the number of characters, or a register, (r c ) , 
containing the number of characters to be written. If BUFFER=namel, 
the COUNT parameter may be omitted, in which case the number of characters 
read will be equal to the buffer length. The number of characters may 
not exceed 256. 

No check will be made to ensure that SYSLOG is assigned to a 1052 
or any other printer. 



(YES) 
,RETURN=|^o-| 

This parameter governs the return to the input section or optional 
user section. If RETURN=YES, a return to the input or user routine is 
provided via register 14. RETURN=NO signifies that the user's own coding 
or additional output utility macro-instructions follow. 
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' OPERATION 


OPERAND 


MUST BE INCLUDED 


REMARKS 




T JSYS002Y" 




If other than 


nnn=programmer logical 


OUTCARD 


H IT -(SYSnnnJ. 




SYS002 is 


unit for output. A 






wanted. 


buffer of 160 bytes is 
generated for the 1442 
and 2520 (240 bytes for 
the 2540) . 


[ ( N0 )1 




If stacker 


Omission, or NO=pocket 2; 




STCTL=<YES > 




selection is 


YES=stacker selection is 




(name). 




desired. 


controlled by first 








character of each record; 








namel=symbolic location 








of area to be inter- 








preted: 0=pocket 2; 








nonzero=YES. 


(1442) 




If other than 


Specifies error- 




,DEVICE=<2520 


> 


a 1442 card 


recovery procedures. 




(2540) 




punch is used. 




T ^ mTT ™ T /YES\" 




If user routine 


NO=continue to next 




L # RETURN-| N0 )_ 




or additional 


sequential statement. 






output utility 


YES=return to input 






macros follow. 


routine or to optional 
user routine. 


OUTAPE 


BUFSIZ=n 


# 

For each file. 


n=maximum size of output 
block. A buffer of 2n 
bytes is generated. 


,BLK=j m A 
' (name 1 J 




If record 
blocking is 


m=blocking factor; value 
of indicates unblocked 






desired. 


records. namel=symbolic 
location to be interro- 
gated. A value of in- 
dicates no blocking is 
performed. Otherwise 
value=blocking factor. 


UNIT _/SYS002) 
,UNIT ^ SYSnnn j 


> 


If other than 
SYS002 is 


nnn=prog rammer logical 
unit for output. 




L- J 


wanted. 




•n-^-r,-, /filename) 


For each file 


Identifies label informa- 




,FILE={ (r) } 


bearing stand- 


tion. r=register pointing 






ard labels. 


to an 8 character filename. 


[,LBL=name2] 


If special label 


name2=fullword area 






processing is 


symbolically designated 






desired. 


name2 to be interpreted. 
If value=0, standard la- 
bels are assumed and user 
labels are bypassed. If 
value is negative, no 
label processing is at- 
tempted; if value is 
positive, value=address 
of user HDR processing 
routine. 



Figure 3. Summary of Output Macro Instructions (Part 1 of 3) 
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OfjekAtiuN 


OPERAND 


MUST BE INCLUDED 


REMARKS 


OUT APE 


,RETURN-< YES } 




If user routine 


NO=continue to next 


(Cont'd) 


I NO ) 




or additional 


sequential statement. 






output utility 


YES=return to input 






macros follow. 


routine or to optional 
user routine. 


OUTDISK 


BUFSIZ=n 


For each file. 


n=maximum size of output 
block. A buffer of 2n 








bytes is generated. 


/m \] 




If record 


m=blocking factor; 




' BLK -(namelj 




blocking is 


value of indicates 






desired . 


unblocked records . 
namel=symbolic location 
to be interrogated. A 
value of indicates no 
blocking is performed. 
Otherwise value=blocking 
factor. 


FILE={ fil ^^ e } 


For each file. 


Identifies label informa- 
tion. r=register point- 








ing to an 8 character 








filename. 


[ , LBL=name2] 


If user label 


name2=fullword area 






processing is 


symbolically designated 






desired. 


name 2 to be interpreted. 
If value=0 , no user HDR 
label processing is 
attempted; if value is 
nonzero, value=address 
of user HDR record proc- 








essing routine. 


r /ignore)" 


If a write 


IGNORE=ignore error 




L/ ERROR= lname3 jj 


check is 


condition. name3=sym- 






desired, 
i 


bolic address of user 
routine for error- 
recording. 


(FULL ) 


When a speci- 


FULL=fill track as much 




,FORMAT=<! n > 


fied number of 


as possible. 




(name 4; 


records are to 


n=number of records per 






appear on each 


track. 






track. 


name4=symbolic address 
containing number 
of records per 
track value. If 
value is 0, FULL 
is assumed. 



Figure 3. Summary of Output Macro Instructions (Part 2 of 3) 
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OPERATION 


OPERAND 


MUST BE INCLUDED 


REMARKS 


OUTDISK 
(Cont'd) 


[,RETURN={^ S }_ 




If user routine 
or additional 
output utility 
macros follow. 


NO=continue to next 
sequential statement. 
YES=return to input 
routine or to optional 
user routine. 


OUTPRT 


[BUFSIZ=n] 


If n should be 
less than 144. 


n=maximum size of output 
block. 


TT . 7Tm /SYS0 02\ 

,UNIT= <_,.,.„ ) 

(SYSnnnJ 




If other than 
SYS002 is 
wanted. 


nnn=programmer logical 
unit for output. 


,FOEMS=<^ > 




If other than 
single -spaced 
lines are 
desired. 


Refer to the description 
of carriage control codes 
provided with macro 
description. 


[, RETURNS {^ S }] 




If user routine 
or additional 
output utility 
macros follow. 


NO=continue to next 
sequential statement. 
YES=return to input 
routine or to optional 
user routine. 


OUTLOG 


BUFFER={^H 


For each output 
on the 1052. 


namel=symbolic location 
of the user's buffer 
area. reregister con- 
taining the buffer ad- 
dress (absolute or 
symbolic) . 


: C0UNT= {"r c )}_ 




If BUFFER=(r b ) 


n=number of characters 
to be written. r = 
register containing 
the number of characters 
to be written. 


[,RETURN={^ S }j 




If user routine 
or additional 
output utility 
macros follow. 


NO=continue to next 
sequential statement. 
YES=return to input 
routine or to optional 
user routine. 



Figure 3. Summary of Output Macro Instructions (Part 3 of 3) 
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EXAMPLES OF UTILITY PROGRAM GENERATION 



CARD-TO- CARD 



A program of this type can be used for detection of an arbitrary data 
delimiter card for card input. 



NAME 


OPERATION 


OPERAND 




START 









INCARD 








BALR 


9,0 


(establish base register) 




USING 


*,9 






LR 


2,0 


(put address of input area into 


* 






register 2) 






\2,2/ , A 


(compare for data delimiter) 




BNE 


B 


(continue with output if not 


* 






delimiter) 




BAL 


14, B 


(punch delimiter card) 




SR 


0,0 


(set registers zero and one to 


* 






zero to signal end of job) 




SR 


1,1 




B 


OUTCARD 






A 


DC 


Q " ** • 


(sets up the arbitrary data 


* 


END 




delimiter) 



Notes : Input unit: SYS001 

Output unit: SYS002; no stacker selection. 
A user exit provides for cards to be read until a ** is 
encountered in card columns 1 and 2 or until end-of-file 
is reached on the reader. 

CARD-TO-DISK 

A program of this type can be used for building a SYSIN file on disk, 



NAME 


OPERATION 


OPERAND 


Col. 
72 




START 

INCARD 

OUTDISK 

END 




BUFSIZ=80,FILE=DASDOUPT,ERROR= 
IGNORE , FORMAT=2 5 


X 



Notes : Input unit: SYS001 

Output unit: symbolic unit obtained from XTENT card; no user 
labels: unblocked output, 80 characters per record; write 
check disk output; ignore write errors; 25 records per track: 
filename DASDOUPT 

No user routines 



Evamnl £*.<=; 
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CARD-TO-PRINTER AND CARD 

A program of this type is used to both print and punch the input 
records. Note the use of the RETURN operand. 



NAME 


OPERATION 


OPERAND 




START 
INCARD 
OUTPRT 
OUTCARD 

END 




BUFSIZ=80 ,RETURN=NO 
UNIT=SYS003,DEVICE=2540 



Notes : Input unit: SYS001 

Printer output unit: SYS002; 80 characters per line; single space 
Card output unit: SYS003; all output into pocket 2; 2540 card punch 
No user routines 

CARD-TO-TAPE 

A program of this type can be used to build a SYSIN file on tape. 



NAME 


OPERATION 


OPERAND 




START 
INCARD 
OUTAPE 
END 



BUFSIZ=80 



Notes : Input unit: SYS001 

Output unit: SYS002; no labels; unblocked output; 
80 characters per record 

No user routines 

DISK-TO-CARD 

A program of this type can be used to punch a SYSPCH file from disk. 



NAME 


OPERATION 


OPERAND 




START 
INDISK 
OUTCARD 
END 




BUFSIZ=81,FILE=DASDINPT 

STCTL=YES 



Notes : Input unit: Symbolic unit obtained from XTENT card; no user 
label; ignore read errors; unblocked input records not longer 
than 81 characters; filename DASDINPT 

Output unit: SYS 002; stacker selection via ASA control characters 

No user routines 
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DISK-TO-PRINTER 

A program of this type can be used to print a SYSLST file from disk. 



NAME 


OPERATION 


OPERAND 




START 

INDISK 

OUTPRT 

END 




BUFSIZ=121,FILE=INPTDASD 

BUFSIZ=121 / FORMS=D 



Notes: input unit: Symbolic unit obtained from XTENT card; no user 

label; ignore read errors; unblocked input records not longer than 
121 bytes; filename INPTDASD 

Output unit: SYS002; forms control via ASA control 
characters 

No user routines 

TAPE -TO- CARD 

A program of this type can be used to punch a SYSPCH file from tape. 



NAME 


OPERATION 


OPERAND 




START 

INTAPE 

OUTCARD 

END 




BUFSIZ=81 / UNIT=SYS002 
STCTL=YE'S , UNIT=SYS 00 3 

i — — 



Notes : Input unit: SYS002; no labels; ignore read errors; 

unblocked input records not more than 81 characters in 
length; bypass checkpoint records 

Output unit: SYS003; stacker selection; 1442 card punch 
No user routines 

TAPE-TO-PRINTER 

A program of this type can be used to print a SYSLST file from tape. 



NAME 


OPERATION 


OPERAND 




START 
INTAPE 
OUTPRT 
END 




BUFSIZ=121 

BUFSIZ=121,UNIT=SYS005,FORMS=D 



Notes : Input unit: SYS001; no labels; ignore read errors: 

unblocked input records not more than 121 bytes long; 
bypass checkpoint records, if any 



Output unit; 
characters 



SYS005; forms control via ASA control 
No user routines 



Examples 
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TAPE-TO-PRINTER AND/OR CARD 

A program of this type will be used to print and punch combined SYSLST/ 
SYSPCH output. A user routine provides for selection of printer or 
punch. Note that the data is assumed to be on a single tape reel and 
preceded by a tapemark. 



NAME 


OPERATION 


OPERAND 






START 









INTAPE 


BUFSIZ=121 


r CHKPT=NO 




BALR 


9,0 






USING 


*,9 


(establish base register) 




LTR 


0,0 


(end of input data?) 




BNZ 


A 


(no) 


C 


NOP 


B 


(skip past first tapemark) 




01 


C+1,X'F0' 


(change NOP to a branch 


* 






instruction) 




BR 


14 


(return to input routine) 


B 


LA 


1,* 


(set to signal end-of-file) 




BAL 


14, PUNCH 


(clear punch output buffers) 




SR 


1,1 


(set to signal end-of-job) 




B 


PRINT 


(clear printer buffers and 


* 






end job) 


A 


LR 


2,0 


(record address into register 2) 




CLI 


0(2) ,X'E5' 


(is control character a V) 




BE 


PUNCH 


(yes--punch card) 




CLI 


0(2) rX'Ee' 


(is control character a W) 




BE 


PUNCH 


(yes--punch card) 


PRINT 


OUTPRT 


BUFSIZ=121 


,FORMS=D,UNIT=SYS003 


PUNCH 


OUTCARD 

END 


STCTL=YES 





Notes : Input unit SYS001; no labels; ignore read errors; no 

checkpoint records; unblocked input records not more than 
121 bytes long 

Output unit: SYS002 (punch) and SYS003 (print); forms 

control and stacker select via ASA control characters; 1442 card punch 

User exit for selection of output 
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ASSEMBLY AND INITIATION OF A GENERATED UTILITY PROGRAM 



Before a generated utility program is executed as either a background 
or foreground program, the utility program must be assembled by the 
assembler. The assembly can be combined with execution or cataloging, 
or both, depending on current job requirements and future plans for 
using the generated program. 

The major considerations in determining the' job setup are: 

1. whether the assembled program is to be cataloged for subsequent 
use, 

2. whether that use is to be a foreground or background program. 

3. whether execution is desired immediately after the assembly. 

In the examples which follow, a card-to-card program is used to 
show the deck organization for some of the available options. 

The first example illustrates the assembly and cataloging of the 
program CDTOCD for subsequent execution as a foreground program. 
The use of zero as a link-edit address is an indication that the 

rMrA/Tr^Tii -i <-< <~* /Ts 1 f-rol /-\/~* o +- n r*i /t T'T-hc* r-\ -v- /~\ /-r -v* ^s m rr\ n t t V\<c* c$ v <q r* n 4- q r\ ^ o o Vs r* /~*\r _ 

ground or foreground job. In the following examples, the job control 
and linkage editor control statements are explained in the System 
Control and System Service publications. 

Example 1: ASSEMBLE & CATALOG CARD-TO-CARD FOR SUBSEQUENT USE AS A 
SELF-RELOCATING PROGRAM 

// JOB CARDCARD 
// OPTION CATAL 
I PHASE CDTOCD, +0 
// EXEC ASSEMBLY 

START 

INCARD 

OUTCARD 

END 

/* 

// EXEC LNKEDT 

A 

The second example illustrates the assembly and cataloging of a 
similar program with user routines, for use as a foreground program. 



+- t a +■ i r\t 



Example 2: ASSEMBLE & CATALOG CARD-TO-CARD FOR SUBSEQUENT USE AS A 
FOREGROUND PROGRAM (Not self-relocating, the foreground 
partition originates at 16384) 

// JOB CARDCARD 
// OPTION CATAL 

PHASE CDTOCD,F+16 384 
// EXEC ASSEMBLY 

START 



Initialization Routine (user-provided, not self-relocating) 



INCARD 

OUTCARD 

END 

/* 

// EXEC LNKEDT 

A 

The third example illustrates the assembly and execution of the same 
utility program as a background job. 

Example 3 : ASSEMBLE & EXECUTE CARD-TO-CARD AS A BACKGROUND PROGRAM 
(Not self-relocating, the program is to load at the 
beginning of the background area) 

// JOB CARDCARD 
// OPTION LINK 

PHASE CDTOCD,S 
// EXEC ASSEMBLY 

START 



Initialization Routine (user-provided, not self-relocating) 



INCARD 

OUTCARD 

END 

/* 

// EXEC LNKEDT 

// ASSGN SYSOOljX'OOC (reader) 

// ASSGN SYS002,X'00D f (punch) 

// EXEC 

/& 

The fourth example combines the cataloging (as in example 2) with 
immediate execution of the cataloged program. 
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Example 4 : ASSEMBLE, CATALOG, & EXECUTE CARD-TO-CARD AS A 
BACKGROUND PROGRAM 

// JOB CARDCARD 
// OPTION CATAL 
I PHASE CDTOCD,+0 
// EXEC ASSEMBLY 

START 

INCARD 

OUTCARD 

END 

/* 

// EXJiC LNKEDT 

// ASSGN SYS001,X'00C (reader) 

// ASSGN SYS002,X'00D* (punch) 

// EXEC 



(card input on reader) 



The fifth example illustrates the control cards needed to execute a 
utility which has been cataloged for use as a background program. 
The catalo^in^ mi^ht have been done by either example 1 or 4 

Example 5 ; EXECUTE PREVIOUSLY CATALOGED CARD-TO-CARD PROGRAM AS A 
BACKGROUND PROGRAM 

// JOB CARDCARD 

// ASSGN SYSOOl^X'OOC (reader) 

// ASSGN SYS002,X'00D' (punch) 

// EXEC CDTOCD 



(card input on reader) 



The execution of a utility program which has been cataloged as a fore- 
ground program is done through SYSLOG and the Foreground Initiator 
rather than SYSRDR and Job Control. 

Example 6 : EXECUTION OF A FOREGROUND PROGRAM WHICH HAS BEEN 
PREVIOUSLY CATALOGED IN THE CORE IMAGE LIBRARY 

COL. 16 COL. 72 

START Fl 

ASSGN SYS001,X'180' (tape drive) 

ASSGN SYS001,X'181' ,ALT (alternate tape drive) 
ASSGN SYS002,X'190' (disk drive) 

ASSGN SYS003,X'191' (second disk drive) 

VOL SYS001,INFILE 
TPLAB 'LABEL FIELDS 3-10' x 

'LABEL FIELDS 11-13' 
VOL SYS002,OUTFILE 
DLAB 'DISKFILE... 1000123',... X 

0001,66030,66430, ' CODEIBM21-3AA 1 
XTENT 1,0,000017006,000017009, '000123' ,SYS002 
XTENT 1,1,0 00086000,000089009, '000123' ,SYS002 
XTENT 128, 2, 000146003,000192007, '000163' ,SYS003 

EXEC TPTODK (previously cataloged tape to disk 

program) 



Foreground programs are initiated by the operator through the 
1052 assigned to SYSLOG. The operator may initiate a foreground 
program whenever the specified foreground area does not contain a 
program. 

The operator initiates a foreground program by depressing the 1052 
request key. 

im 

START (F2j indicates that a foreground program is to be initiated. 
If the area specified is allocated and does not contain a program, 
it transfers control to the Foreground Initiator. Otherwise, the 
operator is notified that he has given an invalid command. 

The Foreground Initiator reads subsequent commands required to 
initiate the program. These commands are used primarily to specify 
I/O assignments and label information. Such information may be read 
from the Printer-Keyboard or Card Reader. 

When DOS is used, each set of label information is composed into 
a label information block and written onto system residence for later 
retrieval and processing by the data management routines. For DOS 
and TOS , a main storage area for label information may be required, 
in which case the area is reserved by the Foreground Initiator. 

When the EXEC command is encountered, the Foreground Initiator 
checks to determine if a self-relocating program is to be loaded. 
(If the load address is zero, the program is self-relocating.) The 
Foreground Initiator will direct this program to be loaded following 
the label information area, if any. A non-self-relocating program 
will be directed to be loaded utilizing the information derived when 
the program was linkage-edited. 

When initial control is given to the user's foreground program, 
register 2 contains the address of the uppermost byte of storage 
available to this program. This may be used to calculate the total 
storage to the program. A foreground program can dynamically deter- 
mine the storage available to it by storing the contents of this 
register for later reference. Foreground initiation commands may be 
referred to in either System Control and System Service publication. 
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